/*
 * Copyright 2016 小新de蜡笔
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef __XML_BEAN_H__
#define __XML_BEAN_H__

/** 每个 XOBJ 对象代表了 xml 中的一个节点。 */
typedef void XOBJ;

/**
 * 创建 XOBJ 对象
 * @param element 由本函数创建对象，并使 element 指向该对象。<br/>
 *	每个 XOBJ 对象代表了 xml 中的一个节点。<br/>
 *	创建对象使用了动态内存管理，所以使用完毕后必须调用 xb_dealloc_xobj(XOBJ*) 函数销毁对象。
 * @param key 是 XOBJ 对象的键，表示 xml 文件中节点的名称。
 * @param val 是 XOBJ 对象的值，表示 xml 文件中节点的值。
 *
 * return 0 表示成功完成 XOBJ 对象的创建。<br/>
 * 	-EINVAL 表示参数非法。<br/>
 * 	-ENOMEM 表示动态内存分配失败。
 */
int xb_new_xobj (XOBJ **element, const char *key, const char *val);

/**
 * 回收由 xb_new_xobj(XOBJ, const char*, const char*) 函数创建的 XOBJ 对象所占用的内存。
 */
void xb_dealloc_xobj (XOBJ *element);

/**
 * 将 XOBJ 节点添加到 DOM 树中。
 * @param parent_element 是 DOM 树中的父节点。
 * @param sub_element 作为 DOM 树中 parent_element 的子节点。
 *
 * return 0 表示成功完成节点添加。<br/>
 * 	-EINVAL 表示参数非法。<br/>
 */
int xb_add_content (XOBJ *parent_element, XOBJ *sub_element);

/**
 * 将 XOBJ 对象转换为字符串形式的 xml 文档。
 * @param element xml 文档的根节点。
 * @param buf 指向生成的 xml 字符串。<br/>
 * 	该 buf 使用了动态内存管理，使用完毕后必须调用 xb_gen_xml_free(char*) 函数进行销毁。
 * @param enable_indent 是否缩进：1 是；0 否。
 *
 * return 0 表示成功解析 DOM 并生成了 xml 字符串。<br/>
 * 	-EINVAL 表示参数非法。<br/>
 * 	-ENOMEM 表示动态内存分配失败。
 */
int xb_gen_xml (XOBJ *element, char **buf, int enable_indent);

/**
 * 回收由 xb_gen_xml(XOBJ*, char**) 函数分配的内存。
 */
void xb_gen_xml_free (char *buf);

#endif

